<?php
/**
 * PureMVC Port to PHP originally translated by Asbjørn Sloth Tønnesen
 *
 * @author Omar Gonzalez :: omar@almerblank.com
 * @author Hasan Otuome :: hasan@almerblank.com
 *
 * Created on Sep 24, 2008
 * PureMVC - Copyright(c) 2006-2008 Futurescale, Inc., Some rights reserved.
 * Your reuse is governed by the Creative Commons Attribution 3.0 Unported License
 */

/**
 * The interface definition for a PureMVC View.
 *
 * <P>
 * In PureMVC, <code>PureMVC_View_Interface</code> implementors assume these responsibilities:</P>
 *
 * <P>
 * In PureMVC, the <code>View</code> class assumes these responsibilities:
 * <UL>
 * <LI>Maintain a cache of <code>IMediator</code> instances.</LI>
 * <LI>Provide methods for registering, retrieving, and removing <code>IMediators</code>.</LI>
 * <LI>Managing the observer lists for each <code>PureMVC_Observer_Notification_Interface</code> in the application.</LI>
 * <LI>Providing a method for attaching <code>PureMVC_Observer_Interface</code> to an <code>PureMVC_Observer_Notification_Interface</code>'s observer list.</LI>
 * <LI>Providing a method for broadcasting an <code>PureMVC_Observer_Notification_Interface</code>.</LI>
 * <LI>Notifying the <code>PureMVC_Observer_Interface</code> of a given <code>PureMVC_Observer_Notification_Interface</code> when it broadcast.</LI>
 * </UL>
 *
 * @see org.puremvc.php.interfaces.IMediator IMediator
 * @see org.puremvc.php.interfaces.IObserver PureMVC_Observer_Interface
 * @see org.puremvc.php.interfaces.PureMVC_Observer_Notification_Interface PureMVC_Observer_Notification_Interface
 */
interface PureMVC_View_Interface
{
  /**
   * Register an <code>PureMVC_Observer_Interface</code> to be notified
   * of <code>PureMVC_Observer_Notification_Interfaces</code> with a given name.
   *
   * @param notificationName the name of the <code>PureMVC_Observer_Notification_Interfaces</code> to notify this <code>PureMVC_Observer_Interface</code> of
   * @param observer the <code>PureMVC_Observer_Interface</code> to register
   */
  public function registerObserver ( $noteName, PureMVC_Observer_Interface $observer );

  /**
   * Notify the <code>PureMVC_Observer_Interface</code> for a particular <code>PureMVC_Observer_Notification_Interface</code>.
   *
   * <P>
   * All previously attached <code>PureMVC_Observer_Interface</code> for this <code>PureMVC_Observer_Notification_Interface</code>'s
   * list are notified and are passed a reference to the <code>PureMVC_Observer_Notification_Interface</code> in
   * the order in which they were registered.</P>
   *
   * @param notification the <code>PureMVC_Observer_Notification_Interface</code> to notify <code>PureMVC_Observer_Interface</code> of.
   */
  public function notifyObservers( PureMVC_Observer_Notification_Interface $note );

  /**
   * Register an <code>IMediator</code> instance with the <code>View</code>.
   *
   * <P>
   * Registers the <code>IMediator</code> so that it can be retrieved by name,
   * and further interrogates the <code>IMediator</code> for its
   * <code>PureMVC_Observer_Notification_Interface</code> interests.</P>
   * <P>
   * If the <code>IMediator</code> returns any <code>PureMVC_Observer_Notification_Interface</code>
   * names to be notified about, an <code>Observer</code> is created encapsulating
   * the <code>IMediator</code> instance's <code>handleNotification</code> method
   * and registering it as an <code>Observer</code> for all <code>PureMVC_Observer_Notification_Interfaces</code> the
   * <code>IMediator</code> is interested in.</p>
   *
   * @param mediatorName the name to associate with this <code>IMediator</code> instance
   * @param mediator a reference to the <code>IMediator</code> instance
   */
  public function registerMediator( PureMVC_Mediator_Interface $mediator );

  /**
   * Retrieve an <code>IMediator</code> from the <code>View</code>.
   *
   * @param mediatorName the name of the <code>IMediator</code> instance to retrieve.
   * @return the <code>IMediator</code> instance previously registered with the given <code>mediatorName</code>.
   */
  public function retrieveMediator( $mediatorName );

  /**
   * Remove an <code>IMediator</code> from the <code>View</code>.
   *
   * @param mediatorName name of the <code>IMediator</code> instance to be removed.
   */
  public function removeMediator( $mediatorName );

  /**
   * Check to see if a Mediator is registered with the View.
   *
   * @param mediatorName name of the <code>IMediator</code> instance to check for.
   */
  public function hasMediator( $mediatorName );

}
